Chapter 05 / StoryCam Development Narrative

StoryCam 工作台视觉连续升级与片段生成合并发布

日期：2026-05-15 类型：产品 UI 迭代 / 流程合并 / PR 发布 主线：Input → Story World → Core Storyboard → Clip Generation

本 session 把 StoryCam 从“分步生成页面”连续推进成更完整的暗色导演工作台体验：输入首页、故事世界、核心分镜和片段生成依次被升级，最终把 clip-review 与 export 合并进 clip-generation，并通过 PR gate 发布到 dev。

本 Session 摘要

时间线

用户原话
“首页storycam/input 做了整体 ui 视觉升级，参照 step_1_update.png，做迭代。”
“我感觉不同层级的文本大小没有参考图那么协调……不要比输入框里用户输入的文本大。”
Codex 总结

输入首页被重构成暗色“导演工作台”：主焦点转向输入胶囊、拍法倾向 chips、最近项目和发现更多影像墙。后续又根据截图反馈压低 chips 与辅助控件字号，避免视觉层级抢过用户输入内容。

结果 / 影响：输入页从 marketing hero 转成任务型创作入口，并形成“视觉参考图 → 实现 → 人眼反馈 → 字号修正”的 UI 协作节奏。

用户原话
“可以建个分支，push 代码，然后提 pr 给 dev。”
“有 ci 没通过……可以更新本地 dev，然后删除多余的分支，准备下一个 feat 开发。”
Codex 总结

围绕输入页迭代完成分支、提交、推送和 PR 流程；CI 问题被反馈后继续修复，并在 merge 后更新本地 dev、删除多余分支。

结果 / 影响：形成每个视觉阶段独立分支和 PR 的发布节奏，为后续 story-world、core-storyboard、clip-generation 迭代复用。

用户原话
“storycam/story-world板块也升级了 ui，如图 story-world_update.png，对该板块做迭代。”
“story-world_update.png可以追踪，然后提 commit，push，提 pr 给 dev。”
Codex 总结

Story World 被改造成“故事世界确认工作台”：非输入页壳层改为 1440px 暗场网格、顶部横向进度；左侧强化剧本确认，右侧重做人物/地点资产区，保留手动生成资产图和资产弹窗能力。

结果 / 影响：StoryCam 的第二步从普通确认页变成可审阅、可编辑、可生成资产图的中间工作台，同时保留原 API 和 E2E 依赖文本。

用户原话
“storycam/core-storyboard板块也升级了 ui，如图 core-storyboard.png，对该板块做迭代升级。”
“滚动查看更多失效；具体一帧画面点击下一张没有变化。”
Codex 总结

核心分镜升级为内联 9 帧工作台：中心主图 + 周围 8 帧扩展画布 + 右侧分镜脚本。用户随后通过截图指出两个交互 bug：脚本列表滚动提示失效、预览弹窗“下一张”不切换。Codex 修正滚动与预览切换逻辑，继续提交和 PR。

结果 / 影响：核心分镜从 modal 主流程转为页面主体验，并通过真实操作反馈修掉了关键交互断点。

用户原话
“.githooks/pre-push，这个不要排除。”
“Add pre-push PR gate guidance after deterministic checks pass。”
Codex 总结

pre-push hook 被纳入版本管理，并在 deterministic checks 通过后提醒运行 StoryCam PR gate。项目发布流程开始明确区分：机械检查由脚本/CI 执行，AI review gate 作为合并前的协作提醒。

结果 / 影响：发布流程从“能 push”升级为“push 时自动提示质量门禁”，降低遗漏 PR gate 的概率。

用户原话
“storycam/clip-generation板块也升级了 ui……clip-review和export两个板块应该是合并到clip-generation里。”
Codex 总结

片段阶段被重构成单页工作台：ProviderSendConfirm、生成状态、片段预览、重拍、最终作品保存和 MP4 导出被聚合到 /storycam/clip-generation。旧的 clip-review / export 只保留兼容映射，不再作为流程步骤。

结果 / 影响：StoryCam 的 MVP 闭环从“多个后续页面”压缩成一个明确的片段生成终点，用户不再在预览和导出之间跳转。

用户原话
“三个步骤的进度条应该要像 ui 视觉图里改造的一样，挪到导航条上。”
“你需要注意下 ui 视觉图，进度条搬到导航栏，要变化的，不要调整导航栏，要改变进度条去匹配导航栏。”
Codex 总结

进度条被迁移到顶部导航栏，并从大尺寸流程 stepper 改成更适合 nav bar 的迷你样式。输入页仍保留首页工作台，非输入页在导航内显示故事世界、核心分镜、片段生成三个步骤。

结果 / 影响：流程感从页面主体抽离到导航层，主内容区域获得更强的视觉焦点。

用户原话
“我觉得图中框出来的两个地方都有多余，都去掉吧，会干净一些，@Chrome 是可以用的，你多试试，我开着网页呢。”
Codex 总结

片段生成页删除重复的视频控制条和多余的下方片段摘要卡，仅保留原生播放器、音频提示、底部 dock 与必要操作。浏览器验证从 Playwright 改为 Chrome 插件 / Computer Use 辅助。

结果 / 影响：页面从“信息重复的工作台”收紧为更干净的生成与导出界面，同时尊重用户指定的浏览器测试方式。

用户原话
“还有现在 seedance 默认用的 720P 还是 1080P，可以将这个参数显示出来。”
“同时要查查默认的啥分辨率。”
“要把分辨率后面都改成显示的 720p，1080p 太贵了。”
Codex 总结

Codex 先从代码和文档判断应显式设置分辨率，随后通过 Chrome 检查火山体验中心发现 Doubao-Seedance-2.0 260128 当前 UI 默认选中 1080p。用户最终从成本角度做出产品决策：StoryCam v1 固定 720p，并在 UI 中显示 输出 720p。

结果 / 影响：这是一个典型的“外部默认值 ≠ 产品默认值”决策。StoryCam 不盲从 provider 默认，而是以成本策略主动锁定输出规格。

用户原话
“包括.codex/config.toml 在内的，可以 commit 了，然后 push，然后 pr 给 dev。”
“跑 PR gate 再开 PR。”
Codex 总结

Codex 将整个 clip-generation 工作树提交到 codex/clip-generation-workstation，push 时触发 pre-push deterministic checks。随后运行 StoryCam PR gate，形成 code-reviewer、security-auditor、test-engineer 三视角 GO 结论，并开 draft PR 到 dev。

结果 / 影响：PR 描述中记录了验证证据、接受风险、覆盖缺口和回滚计划，成为可审阅的工程交付物。

用户原话
“已经 merge，可以更新本地代码准备下一个 feat 开发。”
Codex 总结

本地切回 dev，fast-forward 到 merge 后提交，删除已合并本地分支和远端 feature 分支。Next dev server 修改的 next-env.d.ts 被识别为生成噪音并恢复，不进入版本历史。

结果 / 影响：工作区恢复到干净状态，可以继续下一个 feature；删除远端分支也再次触发 fast gate 并通过。

关键时刻

1. 视觉层级由“实现参考图”进入“用户注意力调优”

问题：输入框下方 chips 与模式按钮一度比用户输入文本还显眼，削弱了创作输入的焦点。

为什么重要：StoryCam 是私人表达入口，用户的那一句故事应该是第一视觉主体。

处理：压低辅助控件字号和布局权重，保留可访问名称与 E2E 依赖文本。

2. 工作流从六步页面收敛成四步导演工作台

问题：clip-generation、clip-review、export 作为独立步骤让后段流程显得碎裂。

为什么重要：MVP 的魔法感来自“生成、预览、保存、导出一口气完成”，不是让用户在多个页面间找状态。

处理：合并到 /storycam/clip-generation，旧路由只做兼容映射。

3. Provider 默认值被产品成本策略覆盖

问题：Seedance 分辨率到底用 720p 还是 1080p，一开始需要查证。

为什么重要：1080p 质量更高但成本更贵，默认值会直接影响真实生成费用。

处理：Chrome 确认火山体验中心默认可见为 1080p；用户决策 StoryCam v1 固定 720p 控成本，并显式写入 provider request。

4. PR gate 把“能跑”升级为“可讲清楚地发布”

问题：UI 大改不只需要代码通过，还要解释风险、覆盖缺口和回滚方式。

为什么重要：StoryCam 进入更复杂的真实 provider 与私有素材阶段，发布质量门禁会影响后续稳定性。

处理：pre-push 跑 deterministic checks，PR gate 汇总代码、安全、测试三视角，并把未跑 Playwright/E2E 作为明确风险记录。

工程证据

版本与 PR

  • Branch: codex/clip-generation-workstation
  • Commit: eca7abc，message 为 Upgrade clip generation workstation
  • PR: #4，标题 [codex] Upgrade clip generation workstation，base 为 dev，先以 draft PR 创建。
  • Merge: 用户确认已 merge；本地随后更新并清理分支。
  • 前序 PR: input、story-world、core-storyboard 各阶段均经历 commit / push / PR / merge 流程，但本 session 内容中未确认具体编号。

检查与验证

  • Fast gate: scripts/pr-ready.sh 通过，包含 lint、typecheck、unit tests、build。
  • Unit tests: Vitest 显示 50 个测试文件、242 个测试通过。
  • Seedance 720p: provider test 断言请求体包含 resolution: "720p"。
  • Pre-push hook: push 和删除远端分支时均触发 deterministic checks 并通过。
  • Browser: 按用户要求使用 Chrome/Computer Use 做人工检查；Playwright/E2E 与 qa:visual 未在本地跑，作为 PR 覆盖缺口记录。

代表性文件变更

  • src/components/storycam/ClipGenerationWorkspace.tsx：新增合并后的片段生成工作台。
  • src/components/storycam/StoryCamWorkspace.tsx：合并流程状态、旧路由兼容映射、顶部导航进度。
  • src/app/globals.css：新增 clip-generation 工作台、导航进度和响应式样式。
  • src/features/storycam/domain/videoSettings.ts：集中定义 Seedance 输出分辨率与 UI label。
  • src/lib/providers/seedance/videoProvider.ts：显式发送 resolution: "720p"。
  • docs/FRONTEND.md、docs/product-specs/storycam-film-machine-design.md、docs/references/providers.md：同步产品、前端和 provider 决策。
  • .codex/config.toml：本次按用户要求纳入提交；PR gate 记录其可能影响 Codex hook reminder。
  • src/components/storycam/ClipGenerationStatus.tsx、ClipReview.tsx、FinalWorkPanel.tsx：删除，职责被合并进新工作台。

对外讲解用总结

这一段开发展示了 StoryCam 如何从“能生成内容的多步骤原型”向“面向普通用户的导演工作台”演进。我们不是简单套设计图，而是逐步把输入、故事世界、核心分镜、片段生成四个阶段都变成有明确焦点的工作台；同时在真实工程流程上保留 API 状态机、登录拦截、最近项目恢复、手动资产生成、旧路由兼容和测试断言。最关键的产品取舍发生在片段生成阶段：预览、重拍、保存和导出被合并到一个页面，用户不用理解内部的 clip-review/export；Seedance 分辨率也从 provider 默认值问题变成 StoryCam 自己的成本策略，最终固定为 720p。这个 session 连接了前面“生成故事世界和分镜”的创作准备，也为后续真实视频生成、成本控制和发布质量门禁打下基础。

后续事项